src: decouple KeyObject and CryptoKey and move CryptoKey to src by panva · Pull Request #62924 · nodejs/node

panva · 2026-04-24T12:56:19Z

Refactors Node.js' Web Crypto CryptoKey implementation to decouple it from KeyObject by moving CryptoKey's internal-slot storage into a new native NativeCryptoKey base and updating internal crypto code to use slot accessors instead of JS-visible properties.

Paired with a future EOL #62321 deprecation (v26.x runtime-deprecation, v27.x EOL) this makes non-extractable CryptoKey key material unreachable in userland 🎉 thanks to removing public access to the [[handle]] internal slot.

Changes:

Introduces NativeCryptoKey (C++) plus JS-side slot helpers (getCryptoKey{Type,Extractable,Algorithm,Usages,Handle}) and updates Web Crypto/internal consumers accordingly.
Migrates Web Crypto key generation/import/export paths from KeyObject wrappers to KeyObjectHandle usage, including structured-clone/worker-transfer support.
Adds targeted regression tests for slot hiding / brand checks / clone-transfer and adds Web Crypto sign/verify benchmarks.

The PR is squash-merged, but the changes are split into logical commits to make review tractable.

Commits

Each commit has a description covering its scope and rationale, see individual commit messages for details. Commits are cumulative (except for fixups and applying feedback). No later commit from the ones listed below revises code introduced by an earlier one. In order:

src: decouple KeyObject and CryptoKey and move CryptoKey to src (empty, just a squash target)
src,crypto: add NativeCryptoKey
lib,crypto: rewire CryptoKey on the native class
lib,crypto: migrate algorithm modules to native CryptoKey
src,crypto: relax RSA/EC keygen arg checks
lib,crypto: validate HkdfParams info length early
lib,crypto: add early structural JWK validation
test: add CryptoKey class regression tests
benchmark: add Web Crypto sign/verify benchmarks
src,lib: switch usages internal slot to a bitmask
++ ... rest is fixups and applying feedback

The PR's changes UI is your friend, either filter commits, or filter files, or both, mark reviewed files as Viewed to remember where you left off.

Benchmark(s)

https://ci.nodejs.org/view/Node.js%20benchmark/job/benchmark-node-micro-benchmarks/1833/
https://ci.nodejs.org/view/Node.js%20benchmark/job/benchmark-node-micro-benchmarks/1834/
https://ci.nodejs.org/view/Node.js%20benchmark/job/benchmark-node-micro-benchmarks/1835/

There's a ton of noise in this to conclude this isn't a performance regression. 🤞

Signed-off-by: Filip Skokan <panva.ip@gmail.com>

nodejs-github-bot · 2026-04-24T12:56:25Z

Review requested:

@nodejs/crypto
@nodejs/performance
@nodejs/cpp-reviewers (for src,crypto: add NativeCryptoKey)

codecov · 2026-04-24T14:18:35Z

Codecov Report

❌ Patch coverage is 91.17647% with 90 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.64%. Comparing base (5d578c5) to head (aedb3e4).
⚠️ Report is 25 commits behind head on main.

Files with missing lines	Patch %	Lines
src/crypto/crypto_keys.cc	71.75%	16 Missing and 34 partials ⚠️
lib/internal/crypto/keys.js	96.69%	9 Missing ⚠️
lib/internal/crypto/webcrypto_util.js	86.56%	9 Missing ⚠️
lib/internal/crypto/webcrypto.js	93.47%	2 Missing and 4 partials ⚠️
src/crypto/crypto_ec.cc	55.55%	2 Missing and 2 partials ⚠️
src/crypto/crypto_keys.h	73.33%	4 Missing ⚠️
lib/internal/crypto/ml_kem.js	92.85%	3 Missing ⚠️
lib/internal/crypto/diffiehellman.js	81.81%	2 Missing ⚠️
lib/internal/crypto/cfrg.js	96.96%	1 Missing ⚠️
lib/internal/crypto/ml_dsa.js	97.61%	1 Missing ⚠️
... and 1 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #62924      +/-   ##
==========================================
- Coverage   89.65%   89.64%   -0.01%     
==========================================
  Files         708      708              
  Lines      220402   220696     +294     
  Branches    42269    42358      +89     
==========================================
+ Hits       197597   197852     +255     
+ Misses      14671    14651      -20     
- Partials     8134     8193      +59

Files with missing lines	Coverage Δ
lib/internal/crypto/aes.js	`92.48% <100.00%> (+2.61%)`	⬆️
lib/internal/crypto/argon2.js	`95.95% <100.00%> (+0.06%)`	⬆️
lib/internal/crypto/chacha20_poly1305.js	`98.42% <100.00%> (+6.42%)`	⬆️
lib/internal/crypto/ec.js	`95.60% <100.00%> (+1.43%)`	⬆️
lib/internal/crypto/hkdf.js	`96.04% <100.00%> (+0.06%)`	⬆️
lib/internal/crypto/mac.js	`98.98% <100.00%> (+6.31%)`	⬆️
lib/internal/crypto/pbkdf2.js	`94.89% <100.00%> (+0.15%)`	⬆️
lib/internal/crypto/util.js	`96.51% <100.00%> (+0.70%)`	⬆️
lib/internal/crypto/webidl.js	`98.39% <100.00%> (+<0.01%)`	⬆️
lib/internal/util/comparisons.js	`99.71% <100.00%> (+<0.01%)`	⬆️
... and 13 more

... and 45 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

panva · 2026-04-24T17:15:28Z

@addaleax thank you for your notes, I hope 65e5612 addresses them.

Edit: now squashed back to its right place

panva · 2026-04-25T19:53:59Z

@anonrig https://github.com/nodejs/node/compare/684325443cbfc5b691465efde509c169c0a87401..db2a2fb8ead37ed8571fa96c5bd5444054556236

Also

fixed a bug that exposed the internal key usages slot in 1a8a0f0
rewrote [[usages]] to be a bitmask in 7bcee80
documented some of the internal helpers in 1af292c

Edit: now squashed back to its right place

panva · 2026-04-26T21:17:32Z

I'm going to autosquash the fixups to restore some notion of coherence when opening the individual commits.

Signed-off-by: Filip Skokan <panva.ip@gmail.com>

panva · 2026-04-29T19:56:50Z

@aduh95 nits resolved (for real this time)

For real real.

Stores the Web Crypto `[[usages]]` slot as a native uint32 mask instead of a JS array. The public and internal usages arrays are now expanded lazily from the mask, while hot-path usage checks can test a bit without allocating or scanning an array. `internal/crypto/util` now derives usage masks from the canonical usage order and exposes helpers for mask conversion and membership checks. CryptoKey import/generation validation uses the zero mask for empty usages, and structured clone / worker transfer serialize the mask too. Signed-off-by: Filip Skokan <panva.ip@gmail.com>

nodejs-github-bot · 2026-04-29T22:41:59Z

CI: https://ci.nodejs.org/job/node-test-pull-request/73037/

nodejs-github-bot · 2026-04-30T04:57:51Z

CI: https://ci.nodejs.org/job/node-test-pull-request/73039/

Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: #62924 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

panva · 2026-05-03T22:09:22Z

Landed in 25f80fb

Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: #62924 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: nodejs#62924 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

panva requested review from addaleax, anonrig, jasnell and tniessen April 24, 2026 12:56

nodejs-github-bot added the needs-ci PRs that need a full CI run. label Apr 24, 2026

addaleax reviewed Apr 24, 2026

View reviewed changes

Comment thread src/crypto/crypto_keys.cc

Comment thread src/crypto/crypto_keys.cc

Comment thread src/crypto/crypto_keys.h Outdated

panva added the request-ci Add this label to start a Jenkins CI on a PR. label Apr 24, 2026

panva force-pushed the native-cryptokey branch 2 times, most recently from 1d88d0c to 6843254 Compare April 25, 2026 11:00

anonrig reviewed Apr 25, 2026

View reviewed changes

panva requested review from addaleax and anonrig April 25, 2026 20:07

panva force-pushed the native-cryptokey branch 3 times, most recently from 1ec62d4 to 9c37d26 Compare April 28, 2026 10:49

ShogunPanda force-pushed the main branch from 2962ccf to 1ad06ff Compare April 28, 2026 12:56

panva added the review wanted PRs that need reviews. label Apr 29, 2026

aduh95 reviewed Apr 29, 2026

View reviewed changes

Comment thread src/crypto/crypto_keys.cc Outdated

aduh95 reviewed Apr 29, 2026

View reviewed changes

Comment thread src/crypto/crypto_keys.cc Outdated

aduh95 reviewed Apr 29, 2026

View reviewed changes

Comment thread test/parallel/test-webcrypto-cryptokey-clone-transfer.js Outdated

doc: document native CryptoKey backing

cbe2cd1

Signed-off-by: Filip Skokan <panva.ip@gmail.com>

panva force-pushed the native-cryptokey branch from 90a0ad3 to a4fd85c Compare April 29, 2026 19:39

This comment was marked as outdated.

Sign in to view

panva force-pushed the native-cryptokey branch 2 times, most recently from c265dcb to 20a35c3 Compare April 29, 2026 19:56

panva force-pushed the native-cryptokey branch from 20a35c3 to aedb3e4 Compare April 29, 2026 19:59

panva added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Apr 30, 2026

panva added a commit that referenced this pull request May 3, 2026

src: decouple KeyObject and CryptoKey and move CryptoKey to src

25f80fb

Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: #62924 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

panva closed this May 3, 2026

panva deleted the native-cryptokey branch May 3, 2026 22:57

panva mentioned this pull request May 4, 2026

crypto: harden KeyObject internal slots and CryptoKey algorithm slots #63111

Closed

aduh95 pushed a commit that referenced this pull request May 5, 2026

src: decouple KeyObject and CryptoKey and move CryptoKey to src

6386914

Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: #62924 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

aduh95 mentioned this pull request May 5, 2026

2026-05-07, Version 26.1.0 #63137

Merged

aduh95 added dont-land-on-v22.x PRs that should not land on the v22.x-staging branch and should not be released in v22.x. dont-land-on-v24.x PRs that should not land on the v24.x-staging branch and should not be released in v24.x. labels May 7, 2026

panva added the dont-land-on-v25.x PRs that should not land on the v25.x-staging branch and should not be released in v25.x. label May 8, 2026

panva mentioned this pull request May 8, 2026

crypto: move DEP0203 and DEP0204 to End-of-Life #63188

Draft

This was referenced May 23, 2026

specs-compliance-issue: crypto.subtle.deriveKey implicit key leak on global Promise pollution #59699

Closed

[v24.x backport] crypto, WebCrypto, and WebIDL updates #63563

Open

panva added backport-open-v24.x Indicate that the PR has an open backport and removed dont-land-on-v24.x PRs that should not land on the v24.x-staging branch and should not be released in v24.x. labels May 25, 2026

panva added a commit to panva/node that referenced this pull request May 25, 2026

src: decouple KeyObject and CryptoKey and move CryptoKey to src

2c21a34

Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: nodejs#62924 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

panva added a commit to panva/node that referenced this pull request May 25, 2026

src: decouple KeyObject and CryptoKey and move CryptoKey to src

8c4066d

Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: nodejs#62924 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

panva added a commit to panva/node that referenced this pull request May 26, 2026

src: decouple KeyObject and CryptoKey and move CryptoKey to src

91dc79b

Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: nodejs#62924 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

araujogui pushed a commit to araujogui/node that referenced this pull request May 26, 2026

src: decouple KeyObject and CryptoKey and move CryptoKey to src

6e0c173

Signed-off-by: Filip Skokan <panva.ip@gmail.com> PR-URL: nodejs#62924 Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Uh oh!

Conversation

panva commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Commits

Benchmark(s)

Uh oh!

nodejs-github-bot commented Apr 24, 2026 • edited by panva Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

panva commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

panva commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

panva commented Apr 26, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

panva commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Apr 29, 2026

Uh oh!

nodejs-github-bot commented Apr 30, 2026

Uh oh!

panva commented May 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

panva commented Apr 24, 2026 •

edited

Loading

nodejs-github-bot commented Apr 24, 2026 •

edited by panva

Loading

codecov Bot commented Apr 24, 2026 •

edited

Loading

panva commented Apr 24, 2026 •

edited

Loading

panva commented Apr 25, 2026 •

edited

Loading

panva commented Apr 29, 2026 •

edited

Loading